Developer Documentation
PATHJava Developer Documentation > Mac OS Runtime for Java > JManager > Programming With JManager

Frame Manipulation Functions

Each applet has one or more frames associated with it. A frame is analogous to a Mac OS window record and usually represents a user window. The following functions let you pass events between a visible user window and the abstract applet frame.


JMSetFrameVisibility

Assigns Mac OS window visibility properties to a frame.

OSStatus JMSetFrameVisibility (
                     JMFrameRef frame,
                     GrafPtr framePort,
                     Point frameOrigin,
                     const RgnHandle frameClip);
frame
The frame whose visibility you want to set.
framePort
The graphics port to assign to the frame.
frameOrigin
The location of the frame's origin, in global coordinates.
frameClip
The clipping region for the frame.
function result
A result code; see JManager Result Codes.

DISCUSSION

You use the JMSetFrameVisibility function to pass Mac OS window visibility elements to the abstract frame. For example, if the user moves the window associated with the frame (by dragging or scrolling), you must update the frame's visibility by passing the new position of the frame in JMSetFrameVisibility .

SEE ALSO

Displaying Frames.

JMGetFrameData

Reads client data associated with a frame.

OSStatus JMGetFrameData (
                     JMFrameRef frame,
                     JMClientData* data);
frame
The frame whose client data you want to read.
data
A pointer to the client data. Upon return, this parameter holds the client data for the frame.
function result
A result code; see JManager Result Codes.

SEE ALSO

Displaying Frames.

The JMSetFrameData function.

JMSetFrameData

Sets or changes the client data for a frame.

OSStatus JMSetFrameData (
                     JMFrameRef frame,
                     JMClientData data);
frame
The frame whose client data you want to set or change.
data
The new client data.
function result
A result code; see JManager Result Codes.

SEE ALSO

Displaying Frames.

The JMSetFrameData function.

JMGetFrameSize

Gets the coordinates of the frame.

OSStatus JMGetFrameSize (
                     JMFrameRef frame,
                     Rect* result);
frame
The frame whose dimensions you want to determine.
result
A pointer to the frame coordinates. Upon return, this parameter holds the coordinates of the frame in pixels.
function result
A result code; see JManager Result Codes.

DISCUSSION

Frames are described using a zero-based coordinate system with the top-left corner of the frame having the coordinates (0,0).

SEE ALSO

The JMSetFrameSize function.


JMSetFrameSize

Sets the size of a frame.

OSStatus JMSetFrameSize (
                     JMFrameRef frame,
                     const Rect* newSize);
frame
The frame whose size you want to set.
newSize
The coordinates of the new frame size in pixels.
function result
A result code; see JManager Result Codes.

DISCUSSION

The function automatically calculates the width and height of the frame, given the coordinates you pass in the newSize parameter. The top left corner indicates the global position of this frame, so you can use this to update the position of the frame if it gets moved.

IMPORTANT

On the Mac OS platform, the global frame coordinates (0,0) does not map to the actual top left corner of the screen, but rather is offset to accomodate the title and side bars of the corresponding window as well as the menu bar.

SEE ALSO

The JMGetFrameSize function.

JMFrameClick

Dispatches a mouse event to a frame.

OSStatus JMFrameClick (
                     JMFrameRef frame,
                     Point localPos,
                     short modifiers);
frame
The frame where the mouse event occurred.
localPos
The position of the mouse in frame coordinates.
modifiers
Any keyboard modifiers from the EventRecord data structure. For more information about EventRecord , see Inside Macintosh: Macintosh Toolbox Essentials.
function result
A result code; see JManager Result Codes.

DISCUSSION

The client application must keep track of the currently active frame.

SEE ALSO

Mouse Events.


JMFrameClickWithEventRecord

Dispatches a mouse event to a frame including event record information.

OSStatus JMFrameClickWithEventRecord (
                     JMFrameRef frame,
                     Point localPos,
                     const EventRecord* event);
frame
The frame where the mouse event occurred.
localPos
The position of the mouse in frame coordinates.
event
A pointer to the event record that describes the mouse event.
function result
A result code; see JManager Result Codes.

DESCRIPTION

Unlike JMFrameClick, JMFrameClickWithEventRecord passes the event record describing the mouse event.

The client application must keep track of the currently active frame.

SEE ALSO

Mouse Events

JMFrameKey

Dispatches a key-down event to a frame.

OSStatus JMFrameKey (JMFrameRef frame,
                     char asciiChar,
                     char keyCode,
                     short modifiers);
frame
The frame in which the key-down event occurred.
asciiChar
The ASCII character typed.
keyCode
The machine key code typed.
modifiers
Any keyboard modifiers from the EventRecord data structure. You can determine the ASCII character (and corresponding machine key code) from EventRecord.message . For more information about EventRecord , see Inside Macintosh: Macintosh Toolbox Essentials.
function result
A result code; see JManager Result Codes.

DISCUSSION

The client application must keep track of the currently active frame.

SEE ALSO

Keyboard Events.

The JMFrameKeyRelease function.


JMFrameKeyRelease

Dispatches a key-up event to a frame.

OSStatus JMFrameKeyRelease (JMFrameRef frame,
                     char asciiChar,
                     char keyCode,
                     short modifiers);
frame
The frame in which the key up event occurred.
asciiChar
The ASCII character typed.
keyCode
The machine key code typed.
modifiers
Any keyboard modifiers from the EventRecord data structure. You can determine the ASCII character (and corresponding machine key code) from EventRecord.message . For more information about EventRecord , see Inside Macintosh: Macintosh Toolbox Essentials.
function result
A result code; see JManager Result Codes.

DISCUSSION

The client application must keep track of the currently active frame.

SEE ALSO

Keyboard Events.

The JMFrameKey function.


JMFrameUpdate

Updates a frame.

OSStatus JMFrameUpdate (
                     JMFrameRef frame,
                     const RgnHandle updateRgn);
frame
The frame to be updated.
updateRgn
The region to be updated, in frame coordinates.
function result
A result code; see JManager Result Codes.

DISCUSSION

The region to update must be specified in frame coordinates, where the top-left corner of the frame has the coordinates (0,0).

SEE ALSO

Update, Activate, and Resume Events.


JMFrameActivate

Activates or deactivates a frame.

OSStatus JMFrameActivate (
                     JMFrameRef frame,
                     Boolean activate);
frame
The frame to be activated or deactivated.
activate
A Boolean value. If true, the frame is to be made active; if false, the frame is to be deactivated.
function result
A result code; see JManager Result Codes.

DISCUSSION

Only one frame should be active at one time, so if you make a frame active, deactivate the other frames in that AWT context thread. The client application must keep track of the currently active frame.

SEE ALSO

Update, Activate, and Resume Events.


JMFrameResume

Passes a resume event to a frame.

OSStatus JMFrameResume (
                     JMFrameRef frame,
                     Boolean resume);
frame
The frame to receive the resume event.
resume
A Boolean value. If true, the process associated with the frame is brought to the foreground; if false, the process is sent to the background.
function result
A result code; see JManager Result Codes.

DISCUSSION

The resume event means that the frame becomes part of the running foreground process. When a client application receives a resume event, it must notify all its associated frames.

SEE ALSO

Update, Activate, and Resume Events.


JMFrameMouseOver

Passes a mouse-over event to a frame.

OSStatus JMFrameMouseOver (
                     JMFrameRef frame,
                     Point localPos,
                     short modifiers);
frame
The frame containing the mouse. This should be the active frame.
localPos
The position of the mouse in frame coordinates.
modifiers
Any keyboard modifiers from the EventRecord structure. See Inside Macintosh: Macintosh Toolbox Essentials, for more information about the EventRecord data structure.
function result
A result code; see JManager Result Codes.

DISCUSSION

To monitor the position of the mouse, you should call the JMFrameMouseOver and JMIdle functions each time through the event loop. Note that the client application must keep track of the currently active frame.


JMFrameShowHide

Shows or hides a frame.

OSStatus JMFrameShowHide (
                     JMFrameRef frame,
                     Boolean showFrame);
frame
The frame to show or hide.
showFrame
A Boolean value. If true, then the frame should be shown; if false, the frame should be hidden.
function result
A result code; see JManager Result Codes.

JMFrameGoAway

Passes a go-away event to the frame.

OSStatus JMFrameGoAway (JMFrameRef frame);
frame
The frame to receive the go-away event.
function result
A result code; see JManager Result Codes.

DISCUSSION

Calling the JMFrameGoAway function disposes of the frame, although in some instances the Java program may want to display a dialog box message (asking if the user wants to save the file before closing, for example).

SEE ALSO

Mouse Events.


JMFrameDragTracking

Passes mouse dragging information to a frame.

OSStatus JMFrameDragTracking (
JMFrameRef frame, DragTrackingMessage message, DragReference theDragRef);
frame
The frame to receive the mouse dragging information.
message
The drag tracking message to pass to the frame. These messages should correspond to the drag tracking messages passed by the Drag Manager to a DragTrackingHandler callback.
theDragRef
The drag reference of the drag.
function result
A result code; see JManager Result Codes.

DISCUSSION

The JMFrameDragTracking function passes drag information to the frame when the user drags an item into the corresponding window. Essentially your application calls this function as though the Drag Manager were calling a DragTrackingHandler callback.

Note that JDK versions 1.1.x and earlier do not support drag and drop.

SEE ALSO

Drag-And-Drop Support.

Drag Manager Programmer's Guide.


JMFrameDragReceive

Passes a drag-and-drop item to a frame.

OSStatus JMFrameDragReceive (
JMFrameRef frame, DragReference theDragRef);
frame
The frame to receive the drag-and-drop information.
theDragRef
The drag reference of the drag.
function result
A result code; see JManager Result Codes.

DISCUSSION

If the user releases a drag in a window corresponding to a frame, you should pass the drag information to the frame using JMFrameDragReceive . The frame can then take action on the drag, depending on the contents of the drag. Essentially your application calls this function as though the Drag Manager were calling a DragReceiveHandler callback.

Note that JDK versions 1.1.x and earlier do not support drag and drop.

SEE ALSO

Drag-And-Drop Support.

Drag Manager Programmer's Guide.


JMGetFrameContext

Returns the AWT context associated with a frame.

JMAWTContextRef JMGetFrameContext (JMFrameRef frame);
frame
The frame whose AWT context you want to determine.
function result
A pointer to the AWT context that owns the frame.

JMGetAWTFrameJNIObject

Returns a JNI reference to a frame's Java object.

extern jobject JMGetAWTFrameJNIObject (
                     JMFrameRef frame,
                     JNIEnv * env);
frame
The frame whose Java object you want to find.
env
A pointer to the current JNIEnv data structure.
function result
A pointer to the java.awt.Frame object associated with the frame.

JMGetAWTFrameObject

Returns a JRI reference to a frame's Java object.

jref JMGetAWTFrameObject(JMFrameRef frame);
frame
The frame whose Java object you want to find.
function result
A pointer to the java.awt.Frame object associated with the frame.

DISCUSSION

Note that unless you specifically need to use the Java Runtime Interface (JRI), you should use the JMGetJMFrameJNIObject function instead.


JMGetJMFrameJNIObject

Returns a JNI reference to a frame's JMFrame object.

extern jobject JMGetJMFrameJNIObject (
                     JMFrameRef frame,
                     JNIEnv * env);
frame
The frame whose Java object you want to find.
env
A pointer to the current JNIEnv data structure.
function result
A pointer to the com.apple.mrj.JManager.JMFrame object associated with the frame.

DESCRIPTION

The JMGetJMFrameObject function returns the Java equivalent of a JMFrameRef reference. A JMFrameRef object encapsulates a Java frame object (that is, a java.awt.Frame object) so it can be handled outside the Java environment.


JMGetJMFrameObject

Returns a JRI reference to a frame's JMFrame object.

jref JMGetJMFrameObject(JMFrameRef frame);
frame
The frame whose Java object you want to find.
function result
A pointer to the com.apple.mrj.JManager.JMFrame object associated with the frame.

DISCUSSION

The JMGetJMFrameObject function returns the Java equivalent of a JMFrameRef reference. A JMFrameRef object encapsulates a Java frame object (that is, a java.awt.Frame object) so it can be handled outside the Java environment.

Note that unless you explicitly need to use the Java Runtime Interface (JRI), you should use the JMGetJMFrameJNIObject function instead.

© 1998 Apple Computer, Inc. — (Last Updated 3 Dec 98)